Enterprise Objects Framework Release 1.1 Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

EODataSources

Adopted By:	EODatabaseDataSource (through EOQualifiableDataSources)
	EODetailDatabaseDataSource (through EOQualifiableDataSources)

Declared In:	eoaccess/EODataSources.h

Protocol Description

The EODataSources protocol defines the interface for a high-level manager of enterprise objects, usually retrieved from some external store, such as an RDBMS. An object conforming to this protocol is called a data-source object (or simply data source). A data-source object provides enterprise objects of a single class, usually corresponding to a single entity in a model (which may in turn correspond to a table in a database). The interface for modifying objects contains only four operations: fetch all objects, insert an object, delete an object, and update an object. This simple interface allows a data source to use nearly any type of storage: a relational database, an array of objects in memory, a file system, a flat-file database, and so on.

A data source typically manages an external data store, translating non-object data into enterprise objects and providing them to your application. In its role as manager, a data source is responsible for explicitly propagating any changes in the objects to the external store; it doesn't ªwatchº the objects to see if they've been edited, but must be sent a message informing it of each edit. For example, to change the ªlastNameº attribute of an enterprise object in the data source's external store, you have to change the enterprise object, then inform the data source with an updateObject: message, and finally save the update with a saveObjects message. Similarly, to insert or delete an enterprise object you use the insertObject: and deleteObject: messages followed by saveObjects.

Also, because a data store can be read-only, you should use the data-source object to create new enterprise objects for insertion. Sending createObject to a data source produces a new enterprise object of the appropriate class if the external store allows editing, and nil if it doesn't. This mechanism allows you to avoid allocating an object only to find that it can't be inserted.

In addition to managing enterprise objects themselves, a data source is responsible for converting values to types that the enterprise objects can use. For example, if an enterprise object stores a ªhireDateº attribute as an NSDate, it may not expect a string representation of a date, and may even cause your application to crash if given one. A data source must be able to convert instances of reasonable value classes to those expected by its enterprise objects. An EODatabaseDataSource, for example, uses information in an EOModel to determine when an NSString value needs to be converted to an NSDate.

By adopting a few other protocols, a data source can offer extra functionality. See the EOQualifiableDataSources, EOMasterDataSources, and EORollbackDataSources protocol specifications for more information.

Method Types

Getting the data-bearing objects	- fetchObjects

Editing objects	- insertObject:
- deleteObject:
- updateObject:
- saveObjects

Creating a new object	- createObject

Converting values to proper types
- coerceValue:forKey:

Accessing attributes of the data source
- canDelete
- keys

Instance Methods

canDelete

- (BOOL)canDelete

Returns YES if the data source allows objects to be deleted, NO if it doesn't.

coerceValue:forKey:

- coerceValue:aValue forKey:(NSString *)key

Returns aValue as an instance of a value class appropriate for the property named by key. For example, EODatabaseDataSource converts values to the value classes defined in an EOModel. Returns nil if aValue couldn't be coerced to the new type.

You should convert any value whose type isn't known to conform to those expected by an enterprise object before passing the value to the object. For example, the Interface Layer's EOController class uses its data source to convert strings received from user-interface objects. The code excerpt below shows how to convert a string representation of an NSCalendarDate for updating by a data-source object:

id <EODataSources> myDataSource;  /* Assume this exists. */
NSString *dateString;             /* Assume this exists. */
id myEO;                          /* Assume this exists. */
id coercedDate;
NSMutableDictionary *dict;

coercedDate = [myDataSource coerceValue:dateString
                            forKey:@"hireDate";]
if (!coercedDate) /* Error... */

dict = [NSDictionary dictionaryWithCapacity:1];
[dict addObject:coercedDate forKey:@"hireDate"];

[myEO takeValuesFromDictionary:dict];
[myDataSource updateObject:myEO];

createObject

- createObject

Returns a new enterprise object with no values set, allocated from the data source's zone and initialized with init, or nil if the data source doesn't allow object insertion. The sender of this message is responsible for setting the enterprise object's property values and for then inserting the newly created object into the data source. For example, if the data source is using a relational database as its external store, the sender must assign the newly created object a valid primary key.

EODatabaseDataSource and EODetailDatabaseDataSource initialize a newly created enterprise object with initWithPrimaryKey:entity: if the enterprise object responds to that method.

See also:  - insertObject:

deleteObject:

- (BOOL)deleteObject:anEO

Deletes anEO from the data source. Returns YES on success, NO on failure.

See also:  - canDelete

fetchObjects

- (NSArray *)fetchObjects

Returns the data-bearing objects provided by the data source, possibly including those that have been inserted but not saved. The fetched objects are allocated from the data source's zone, if possible. If you need to specify the zone from which the fetched objects are to be allocated, retrieve them using EODatabaseChannel's fetchWithZone: method. 

Note that if a data source has been qualified in some manner, it may provide fewer objects than it actually manages. If an error occurs during the fetch, fetchObjects returns nil.

insertObject:

- (BOOL)insertObject:anEO

Inserts anEO into the data source. Returns YES on success, NO on failure.

keys

- (NSArray *)keys

Returns the keys that name the properties of the data source's enterprise objects, for example, ªlastNameº, ªfirstNameº, ªhireDateº, and so on. These are also the names of the class properties for the data source's entity if the data source uses information from an EOModel (see the EODatabaseDataSource class specification).

See also:  - classPropertyNames (EOEntity)

saveObjects

- (BOOL)saveObjects

Saves modified objects to persistent storage (for example, an EODatabaseDataSource does this by committing a transaction). Returns YES on success, NO on failure.

updateObject:

- (BOOL)updateObject:anEO

Updates anEO in the data source. Returns YES on success, NO on failure.